# --------------------------------------------------------
# Swin Transformer
# Copyright (c) 2021 Microsoft
# Licensed under The MIT License [see LICENSE for details]
# Written by Ze Liu
# --------------------------------------------------------

import torch
import torch.nn as nn
import torch.utils.checkpoint as checkpoint
from timm.models.layers import DropPath, to_2tuple, trunc_normal_

try:
    import os, sys

    kernel_path = os.path.abspath(os.path.join('..'))
    sys.path.append(kernel_path)
    from kernels.window_process.window_process import WindowProcess, WindowProcessReverse

except:
    WindowProcess = None
    WindowProcessReverse = None
    print("[Warning] Fused window process have not been installed. Please refer to get_started.md for installation.")


class Mlp(nn.Module):
    """
    多层感知机（MLP）模块，用于Swin Transformer中的前馈网络部分。
    包含两个全连接层，中间带有激活函数和Dropout层。

    参数:
        in_features (int): 输入特征维度
        hidden_features (int, optional): 隐藏层维度，默认为in_features
        out_features (int, optional): 输出特征维度，默认为in_features
        act_layer (nn.Module, optional): 激活函数类型，默认为GELU
        drop (float, optional): Dropout概率，默认为0（不丢弃）
    """

    def __init__(self, in_features, hidden_features=None, out_features=None, act_layer=nn.GELU, drop=0.):
        super().__init__()  # 调用父类nn.Module的初始化方法
        out_features = out_features or in_features  # 如果未指定out_features，则使用in_features
        hidden_features = hidden_features or in_features  # 如果未指定hidden_features，则使用in_features

        # 第一全连接层（扩展维度）
        self.fc1 = nn.Linear(in_features, hidden_features)

        # 激活函数（默认GELU）
        self.act = act_layer()

        # 第二全连接层（恢复维度）
        self.fc2 = nn.Linear(hidden_features, out_features)

        # Dropout层
        self.drop = nn.Dropout(drop)

        print("Mlp模块初始化完成")  # 调试信息

    def forward(self, x):
        """
        前向传播过程:
        1. 通过第一个全连接层扩展维度
        2. 应用激活函数
        3. 执行第一次Dropout
        4. 通过第二个全连接层恢复维度
        5. 执行第二次Dropout

        参数:
            x (Tensor): 输入张量，形状为[B, N, C]，其中B是batch大小，N是序列长度，C是特征维度

        返回:
            Tensor: 输出张量，形状与输入相同（当out_features=in_features时）
        """
        # 第一全连接层 + 激活 + Dropout
        x = self.fc1(x)  # 形状变化: [B, N, in_features] -> [B, N, hidden_features]
        x = self.act(x)  # 保持形状不变，逐元素激活
        x = self.drop(x)  # 随机置零部分神经元

        # 第二全连接层 + Dropout
        x = self.fc2(x)  # 形状变化: [B, N, hidden_features] -> [B, N, out_features]
        x = self.drop(x)  # 最终输出Dropout

        return x


def window_partition(x, window_size):
    """
    将输入特征图划分为不重叠的局部窗口

    参数:
        x (Tensor): 输入特征图，形状为 [B, H, W, C]
            B: batch大小
            H: 特征图高度
            W: 特征图宽度
            C: 通道数
        window_size (int): 窗口大小（正方形窗口）

    返回:
        Tensor: 划分后的窗口集合，形状为 [num_windows*B, window_size, window_size, C]
            num_windows = (H // window_size) * (W // window_size)
    """
    # 获取输入张量的形状（第10行）
    B, H, W, C = x.size()  # 等价于 x.shape（第11行重复获取，可删除）

    # 将特征图划分为网格状的窗口（第12行）
    # 原始形状 [B, H, W, C] ->
    # [B, H//ws, ws, W//ws, ws, C]（其中ws表示window_size）
    x = x.view(
        B,  # 保持batch维度不变
        H // window_size,  # 高度方向划分的窗口数
        window_size,  # 每个窗口的高度
        W // window_size,  # 宽度方向划分的窗口数
        window_size,  # 每个窗口的宽度
        C  # 保持通道维度不变
    )

    # 调整维度顺序并合并窗口（第13行）
    # 操作分解：
    # 1. permute(0,1,3,2,4,5): 将窗口高度和宽度维度相邻
    #    [B, H//ws, W//ws, ws, ws, C]
    # 2. contiguous(): 确保内存连续（加速后续操作）
    # 3. view(-1, ws, ws, C): 将所有窗口展平为batch维度
    windows = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(
        -1,  # 自动计算：B * (H//ws) * (W//ws)
        window_size,  # 窗口高度
        window_size,  # 窗口宽度
        C  # 通道数
    )

    return windows


def window_reverse(windows, window_size, H, W):
    """
    将划分后的窗口恢复为原始特征图形状，与window_partition操作互逆

    参数:
        windows (Tensor): 窗口数据，形状为 [num_windows*B, ws, ws, C]
            num_windows = (H // window_size) * (W // window_size)
            ws: window_size
        window_size (int): 窗口大小（必须与划分时一致）
        H (int): 目标特征图高度
        W (int): 目标特征图宽度

    返回:
        Tensor: 恢复后的特征图，形状为 [B, H, W, C]

    计算过程:
        1. 计算原始batch大小 B
        2. 重组窗口为网格结构
        3. 调整维度顺序恢复空间排列
    """
    # 步骤1：计算原始batch大小（第12行）
    # 公式推导：
    # num_windows = (H // ws) * (W // ws)
    # windows.shape[0] = num_windows * B
    # => B = windows.shape[0] / ((H//ws) * (W//ws))
    B = int(windows.shape[0] / ((H * W) / (window_size * window_size)))

    # 步骤2：重组窗口为网格结构（第13行）
    # [num_windows*B, ws, ws, C] ->
    # [B, H//ws, W//ws, ws, ws, C]
    x = windows.view(
        B,  # Batch维度
        H // window_size,  # 高度方向窗口数
        W // window_size,  # 宽度方向窗口数
        window_size,  # 窗口高度
        window_size,  # 窗口宽度
        -1  # 自动推断通道数
    )

    # 步骤3：调整维度顺序并合并（第14行）
    # 操作分解：
    # 1. permute(0,1,3,2,4,5): 交换高度/宽度窗口维度
    #    [B, H//ws, ws, W//ws, ws, C]
    # 2. contiguous(): 确保内存连续
    # 3. view(B, H, W, -1): 合并为原始特征图形状
    x = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(
        B,  # 保持Batch维度
        H,  # 恢复原始高度
        W,  # 恢复原始宽度
        -1  # 保持通道数
    )

    return x


class WindowAttention(nn.Module):
    """基于窗口的多头自注意力模块（W-MSA），带有相对位置偏置
    支持常规窗口和移位窗口两种模式

    参数:
        dim (int): 输入通道数（特征维度）
        window_size (tuple[int]): 窗口的高和宽（Wh, Ww）
        num_heads (int): 注意力头的数量
        qkv_bias (bool, 可选): 是否为query/key/value添加可学习偏置，默认为True
        qk_scale (float | None, 可选): 覆盖默认的head_dim**-0.5缩放因子
        attn_drop (float, 可选): 注意力权重的dropout比率，默认为0
        proj_drop (float, 可选): 输出投影的dropout比率，默认为0
    """

    def __init__(self, dim, window_size, num_heads, qkv_bias=True, qk_scale=None,
                 attn_drop=0., proj_drop=0.):
        super().__init__()
        # 基础参数设置
        self.dim = dim  # 输入特征维度
        self.window_size = window_size  # 窗口尺寸 (Wh, Ww)
        self.num_heads = num_heads  # 注意力头数
        head_dim = dim // num_heads  # 每个头的维度
        self.scale = qk_scale or head_dim ** -0.5  # 注意力分数缩放因子

        # --- 相对位置偏置表 ---
        # 构建一个可学习的相对位置偏置表
        # 表格大小：(2*Wh-1)*(2*Ww-1) x num_heads
        self.relative_position_bias_table = nn.Parameter(
            torch.zeros((2 * window_size[0] - 1) * (2 * window_size[1] - 1), num_heads))

        # --- 相对位置索引计算 ---
        # 为窗口内的每个token计算成对的相对位置索引
        coords_h = torch.arange(self.window_size[0])  # [0, 1,..., Wh-1]
        coords_w = torch.arange(self.window_size[1])  # [0, 1,..., Ww-1]

        # 构建坐标网格 [2, Wh, Ww]
        coords = torch.stack(torch.meshgrid([coords_h, coords_w]))

        # 展平坐标 [2, Wh*Ww]
        coords_flatten = torch.flatten(coords, 1)

        # 计算相对坐标 [2, Wh*Ww, Wh*Ww]
        relative_coords = coords_flatten[:, :, None] - coords_flatten[:, None, :]

        # 调整维度顺序 [Wh*Ww, Wh*Ww, 2]
        relative_coords = relative_coords.permute(1, 2, 0).contiguous()

        # 将坐标偏移到非负数范围
        relative_coords[:, :, 0] += self.window_size[0] - 1  # 行坐标偏移
        relative_coords[:, :, 1] += self.window_size[1] - 1  # 列坐标偏移

        # 将行列坐标转换为唯一索引
        relative_coords[:, :, 0] *= 2 * self.window_size[1] - 1
        relative_position_index = relative_coords.sum(-1)  # [Wh*Ww, Wh*Ww]

        # 注册为不参与学习的缓冲区
        self.register_buffer("relative_position_index", relative_position_index)

        # --- 注意力计算层 ---
        self.qkv = nn.Linear(dim, dim * 3, bias=qkv_bias)  # QKV投影
        self.attn_drop = nn.Dropout(attn_drop)  # 注意力dropout
        self.proj = nn.Linear(dim, dim)  # 输出投影
        self.proj_drop = nn.Dropout(proj_drop)  # 输出dropout

        # 初始化
        trunc_normal_(self.relative_position_bias_table, std=.02)
        self.softmax = nn.Softmax(dim=-1)

    def forward(self, x, mask=None):
        """
        前向传播

        参数:
            x: 输入特征 [num_windows*B, N, C]
            mask: (0/-inf)掩码 [num_windows, Wh*Ww, Wh*Ww] 或 None

        返回:
            输出特征 [num_windows*B, N, C]
        """
        B_, N, C = x.shape  # B_ = num_windows*B

        # 1. QKV投影 [B_, N, 3*C] -> [3, B_, num_heads, N, head_dim]
        qkv = self.qkv(x).reshape(B_, N, 3, self.num_heads, C // self.num_heads).permute(2, 0, 3, 1, 4)
        q, k, v = qkv[0], qkv[1], qkv[2]  # 每个[B_, num_heads, N, head_dim]

        # 2. 缩放点积注意力
        q = q * self.scale  # 缩放Q
        attn = (q @ k.transpose(-2, -1))  # [B_, num_heads, N, N]

        # 3. 添加相对位置偏置
        relative_position_bias = self.relative_position_bias_table[
            self.relative_position_index.view(-1)].view(  # [Wh*Ww*Wh*Ww, num_heads]
            self.window_size[0] * self.window_size[1],
            self.window_size[0] * self.window_size[1],
            -1)  # [Wh*Ww, Wh*Ww, num_heads]

        relative_position_bias = relative_position_bias.permute(2, 0, 1).contiguous()  # [num_heads, Wh*Ww, Wh*Ww]
        attn = attn + relative_position_bias.unsqueeze(0)  # [B_, num_heads, N, N]

        # 4. 应用掩码（如果存在）
        if mask is not None:
            nW = mask.shape[0]  # 窗口数量
            # 重塑注意力矩阵以添加掩码
            attn = attn.view(B_ // nW, nW, self.num_heads, N, N) + mask.unsqueeze(1).unsqueeze(0)
            attn = attn.view(-1, self.num_heads, N, N)
            attn = self.softmax(attn)
        else:
            attn = self.softmax(attn)

        # 5. 注意力dropout
        attn = self.attn_drop(attn)

        # 6. 值向量加权求和 [B_, num_heads, N, head_dim]
        x = (attn @ v).transpose(1, 2).reshape(B_, N, C)

        # 7. 输出投影和dropout
        x = self.proj(x)
        x = self.proj_drop(x)

        return x

    def extra_repr(self) -> str:
        """
        自定义模块的额外表示信息，用于打印模型结构时显示关键参数

        返回:
            str: 包含以下参数的格式化字符串:
                - dim: 输入特征维度
                - window_size: 窗口尺寸 (Wh, Ww)
                - num_heads: 注意力头数量

        示例:
            >>> layer = WindowAttention(dim=128, window_size=(7,7), num_heads=4)
            >>> print(layer)
            WindowAttention(
              (qkv): Linear(...)
              (attn_drop): Dropout(...)
              (proj): Linear(...)
              (proj_drop): Dropout(...)
              dim=128, window_size=(7, 7), num_heads=4
            )
        """
        return f'dim={self.dim}, window_size={self.window_size}, num_heads={self.num_heads}'

    def flops(self, N):
        # calculate flops for 1 window with token length of N
        flops = 0
        # qkv = self.qkv(x)
        flops += N * self.dim * 3 * self.dim
        # attn = (q @ k.transpose(-2, -1))
        flops += self.num_heads * N * (self.dim // self.num_heads) * N
        #  x = (attn @ v)
        flops += self.num_heads * N * N * (self.dim // self.num_heads)
        # x = self.proj(x)
        flops += N * self.dim * self.dim
        return flops


class SwinTransformerBlock(nn.Module):
    """Swin Transformer 基础模块，包含窗口多头自注意力和前馈网络

    参数:
        dim (int): 输入通道数
        input_resolution (tuple[int]): 输入特征图分辨率 (H, W)
        num_heads (int): 注意力头数量
        window_size (int): 局部窗口大小
        shift_size (int): 移位窗口的偏移量（SW-MSA）
        mlp_ratio (float): MLP隐藏层维度扩展比例
        qkv_bias (bool): 是否为QKV添加可学习偏置
        qk_scale (float): 覆盖默认的注意力缩放因子
        drop (float): 常规dropout比率
        attn_drop (float): 注意力dropout比率
        drop_path (float): 随机深度衰减比率
        act_layer (nn.Module): 激活函数类型
        norm_layer (nn.Module): 归一化层类型
        fused_window_process (bool): 是否使用融合窗口处理加速
    """

    def __init__(self, dim, input_resolution, num_heads, window_size=7, shift_size=0,
                 mlp_ratio=4., qkv_bias=True, qk_scale=None, drop=0., attn_drop=0., drop_path=0.,
                 act_layer=nn.GELU, norm_layer=nn.LayerNorm, fused_window_process=False):
        super().__init__()
        # 第1部分：基础参数设置
        self.dim = dim  # 输入特征维度 [C]
        self.input_resolution = input_resolution  # 输入特征图尺寸 [H, W]
        self.num_heads = num_heads  # 注意力头数量
        self.window_size = window_size  # 局部窗口大小
        self.shift_size = shift_size  # 窗口移位步长
        self.mlp_ratio = mlp_ratio  # MLP扩展比例

        # 第2部分：窗口尺寸自适应处理
        if min(self.input_resolution) <= self.window_size:
            # 当输入分辨率小于窗口大小时，禁用移位并调整窗口尺寸
            self.shift_size = 0
            self.window_size = min(self.input_resolution)
        assert 0 <= self.shift_size < self.window_size, "shift_size必须在[0, window_size)范围内"

        # 第3部分：构建窗口注意力模块
        self.norm1 = norm_layer(dim)  # 前置LayerNorm
        self.attn = WindowAttention(
            dim,
            window_size=to_2tuple(self.window_size),  # 窗口尺寸转为(H,W)格式
            num_heads=num_heads,
            qkv_bias=qkv_bias,  # QKV线性层的偏置
            qk_scale=qk_scale,  # 注意力缩放因子
            attn_drop=attn_drop,  # 注意力dropout
            proj_drop=drop  # 输出投影dropout
        )

        # 第4部分：随机深度衰减设置
        self.drop_path = DropPath(drop_path) if drop_path > 0. else nn.Identity()

        # 第5部分：前馈网络构建
        self.norm2 = norm_layer(dim)  # 前置LayerNorm
        mlp_hidden_dim = int(dim * mlp_ratio)  # MLP隐藏层维度
        self.mlp = Mlp(
            in_features=dim,  # 输入维度
            hidden_features=mlp_hidden_dim,  # 隐藏层维度
            act_layer=act_layer,  # 激活函数
            drop=drop  # dropout比率
        )

        # 第6部分：移位窗口掩码生成
        if self.shift_size > 0:
            # 仅当使用移位窗口时需要生成掩码
            self._generate_attention_mask()
        else:
            # 常规窗口注意力无需掩码
            self.register_buffer("attn_mask", None)

        # 第7部分：窗口处理加速标志
        self.fused_window_process = fused_window_process

    def _generate_attention_mask(self):
        """为移位窗口注意力生成掩码矩阵"""
        H, W = self.input_resolution
        # 初始化全零掩码矩阵 [1, H, W, 1]
        img_mask = torch.zeros((1, H, W, 1))

        # 定义高度方向的切片范围
        h_slices = (
            slice(0, -self.window_size),  # 上方区域
            slice(-self.window_size, -self.shift_size),  # 中间区域
            slice(-self.shift_size, None)  # 下方区域
        )
        # 定义宽度方向的切片范围
        w_slices = (
            slice(0, -self.window_size),  # 左侧区域
            slice(-self.window_size, -self.shift_size),  # 中部区域
            slice(-self.shift_size, None)  # 右侧区域
        )

        # 为9个区域分配不同标记值
        cnt = 0
        for h in h_slices:
            for w in w_slices:
                img_mask[:, h, w, :] = cnt
                cnt += 1

        # 窗口划分后计算掩码
        mask_windows = window_partition(img_mask, self.window_size)  # [nW, ws, ws, 1]
        mask_windows = mask_windows.view(-1, self.window_size * self.window_size)  # [nW, ws*ws]

        # 生成注意力掩码（不同区域间为-100，同区域为0）
        attn_mask = mask_windows.unsqueeze(1) - mask_windows.unsqueeze(2)  # [nW, 1, ws*ws] - [nW, ws*ws, 1]
        attn_mask = attn_mask.masked_fill(attn_mask != 0, float(-100.0))  # 不同区域赋极大负值
        attn_mask = attn_mask.masked_fill(attn_mask == 0, float(0.0))  # 相同区域赋零

        # 注册为不参与学习的缓冲区
        self.register_buffer("attn_mask", attn_mask)

    def forward(self, x):
        """前向传播过程
        参数:
            x: 输入张量 [B, L, C], L=H*W
        返回:
            输出张量 [B, L, C]
        """
        H, W = self.input_resolution
        B, L, C = x.shape
        assert L == H * W, "输入特征尺寸必须满足 L=H*W"

        # ========== 第1部分：窗口注意力 ==========
        # 保留残差连接
        shortcut = x

        # 归一化处理
        x = self.norm1(x)
        # 调整张量形状 [B, H, W, C]
        x = x.view(B, H, W, C)

        # 移位窗口处理
        if self.shift_size > 0:
            if not self.fused_window_process:
                # 常规实现：循环移位+窗口划分
                shifted_x = torch.roll(x, shifts=(-self.shift_size, -self.shift_size), dims=(1, 2))
                x_windows = window_partition(shifted_x, self.window_size)  # [nW*B, ws, ws, C]
            else:
                # 加速实现：使用融合CUDA核
                x_windows = WindowProcess.apply(x, B, H, W, C, -self.shift_size, self.window_size)
        else:
            # 无移位情况
            shifted_x = x
            x_windows = window_partition(shifted_x, self.window_size)

        # 调整窗口形状 [nW*B, ws*ws, C]
        x_windows = x_windows.view(-1, self.window_size * self.window_size, C)

        # 执行窗口注意力计算
        attn_windows = self.attn(x_windows, mask=self.attn_mask)  # [nW*B, ws*ws, C]

        # 恢复窗口形状 [nW*B, ws, ws, C]
        attn_windows = attn_windows.view(-1, self.window_size, self.window_size, C)

        # 窗口合并与逆移位
        if self.shift_size > 0:
            if not self.fused_window_process:
                # 常规实现：窗口合并+逆循环移位
                shifted_x = window_reverse(attn_windows, self.window_size, H, W)  # [B, H, W, C]
                x = torch.roll(shifted_x, shifts=(self.shift_size, self.shift_size), dims=(1, 2))
            else:
                # 加速实现：使用融合CUDA核
                x = WindowProcessReverse.apply(attn_windows, B, H, W, C, self.shift_size, self.window_size)
        else:
            # 无移位情况直接合并窗口
            shifted_x = window_reverse(attn_windows, self.window_size, H, W)
            x = shifted_x

        # 恢复形状并添加残差连接 [B, H*W, C]
        x = x.view(B, H * W, C)
        x = shortcut + self.drop_path(x)

        # ========== 第2部分：前馈网络 ==========
        # 残差连接+MLP
        x = x + self.drop_path(self.mlp(self.norm2(x)))

        return x

    def extra_repr(self) -> str:
        """模块信息补充说明"""
        return f"dim={self.dim}, input_resolution={self.input_resolution}, " \
               f"num_heads={self.num_heads}, window_size={self.window_size}, " \
               f"shift_size={self.shift_size}, mlp_ratio={self.mlp_ratio}"

    def flops(self):
        """
        计算该模块的浮点运算量(FLOPs)

        返回:
            int: 总FLOPs数量

        注意:
            1. 仅计算乘加操作(每个乘加计为1 FLOP)
            2. 忽略非线性操作(如GELU, Softmax)的计算量
            3. 假设所有矩阵乘法都是密集计算
        """
        flops = 0  # 初始化FLOPs计数器
        H, W = self.input_resolution  # 获取输入特征图的高度和宽度

        # 1. 第一个LayerNorm的计算量 (norm1)
        # LayerNorm的FLOPs = 2 * dim * H * W (均值+方差计算)
        flops += self.dim * H * W  # 这里简化为dim*H*W，实际应为2*dim*H*W

        # 2. 窗口注意力计算量 (W-MSA/SW-MSA)
        # 计算窗口数量 nW = (H*W)/(window_size*window_size)
        nW = H * W / self.window_size / self.window_size
        # 每个窗口的FLOPs由attn.flops()计算，再乘以窗口数量
        flops += nW * self.attn.flops(self.window_size * self.window_size)

        # 3. MLP前馈网络计算量
        # MLP包含两个全连接层:
        #   - 第一层: dim -> dim*mlp_ratio
        #   - 第二层: dim*mlp_ratio -> dim
        # 每个全连接的FLOPs = 2 * input_dim * output_dim * H * W
        flops += 2 * H * W * self.dim * self.dim * self.mlp_ratio

        # 4. 第二个LayerNorm的计算量 (norm2)
        # 同第一个LayerNorm
        flops += self.dim * H * W

        return flops  # 返回总FLOPs数


class PatchMerging(nn.Module):
    """Patch Merging层，用于Swin Transformer的下采样阶段

    功能:
        1. 将相邻2x2的patch合并为1个patch（空间分辨率减半）
        2. 通过线性变换将通道数从4C降为2C（类似卷积的下采样）

    参数:
        input_resolution (tuple[int]): 输入特征图的分辨率 (H, W)
        dim (int): 输入特征的通道数 (C)
        norm_layer (nn.Module): 归一化层类型，默认为LayerNorm
    """

    def __init__(self, input_resolution, dim, norm_layer=nn.LayerNorm):
        super().__init__()
        # 初始化参数
        self.input_resolution = input_resolution  # 输入特征图尺寸 (H, W)
        self.dim = dim  # 输入通道数 (C)

        # 定义线性变换层：将4C维特征压缩到2C维
        self.reduction = nn.Linear(4 * dim, 2 * dim, bias=False)

        # 定义归一化层：在通道维度对4C维特征归一化
        self.norm = norm_layer(4 * dim)

        print("初始化Patch Merging Layer")

    def forward(self, x):
        """
        前向传播过程

        参数:
            x: 输入特征张量 [B, H*W, C]

        返回:
            输出特征张量 [B, (H/2)*(W/2), 2C]

        处理流程:
            1. 将序列格式的特征恢复为空间格式
            2. 按2x2网格采样相邻特征
            3. 通道维度拼接
            4. 归一化处理
            5. 线性投影降维
        """
        H, W = self.input_resolution  # 获取输入特征图尺寸
        B, L, C = x.shape  # 输入张量形状 [Batch, Length, Channels]

        # 验证输入尺寸合法性
        assert L == H * W, f"输入特征长度{L}必须等于H*W={H * W}"
        assert H % 2 == 0 and W % 2 == 0, f"特征图尺寸{H}x{W}必须能被2整除"

        # 步骤1：将序列格式转换为空间格式 [B, H, W, C]
        x = x.view(B, H, W, C)

        # 步骤2：按2x2网格采样特征（空间分辨率减半）
        x0 = x[:, 0::2, 0::2, :]  # 左上角特征 [B, H/2, W/2, C]
        x1 = x[:, 1::2, 0::2, :]  # 左下角特征
        x2 = x[:, 0::2, 1::2, :]  # 右上角特征
        x3 = x[:, 1::2, 1::2, :]  # 右下角特征

        # 步骤3：在通道维度拼接 [B, H/2, W/2, 4*C]
        x = torch.cat([x0, x1, x2, x3], dim=-1)

        # 步骤4：展平空间维度 [B, (H/2)*(W/2), 4*C]
        x = x.view(B, -1, 4 * C)

        # 步骤5：应用LayerNorm归一化
        x = self.norm(x)

        # 步骤6：线性投影降维 [B, (H/2)*(W/2), 2*C]
        x = self.reduction(x)

        return x

    def extra_repr(self) -> str:
        """打印模块的额外信息"""
        return f"input_resolution={self.input_resolution}, dim={self.dim}"

    def flops(self):
        """
        计算PatchMerging层的浮点运算量(FLOPs)

        返回:
            int: 该层总FLOPs数量

        计算说明:
            1. 包含两部分计算量：
               - 归一化层(LayerNorm)的计算量
               - 线性投影层(reduction)的计算量
            2. 忽略张量reshape等操作的FLOPs
            3. 以乘加操作(MAC)为基本单位(1 MAC = 2 FLOPs)
        """
        H, W = self.input_resolution  # 获取输入特征图的高度和宽度

        # 第一部分：LayerNorm的计算量
        # 计算公式: 2 * 特征长度 * 特征维度
        # 其中:
        # - 特征长度 = (H//2)*(W//2) (下采样后)
        # - 特征维度 = 4*self.dim (拼接后)
        # 简化计算为: H * W * self.dim (按输入尺寸估算)
        flops = H * W * self.dim

        # 第二部分：线性投影的计算量
        # 计算公式: 2 * 输入维度 * 输出维度 * 输出长度
        # 其中:
        # - 输入维度 = 4*self.dim (拼接后)
        # - 输出维度 = 2*self.dim (降维后)
        # - 输出长度 = (H//2)*(W//2) (下采样后)
        flops += (H // 2) * (W // 2) * 4 * self.dim * 2 * self.dim

        return flops


class BasicLayer(nn.Module):
    """Swin Transformer的单个阶段层，包含多个Swin Transformer块和可选的Patch Merging下采样层

    Args:
        dim (int): 输入特征通道数
        input_resolution (tuple[int]): 输入特征图分辨率 (H, W)
        depth (int): 当前阶段包含的Swin Transformer块数量
        num_heads (int): 多头注意力机制的头数
        window_size (int): 局部窗口大小
        mlp_ratio (float): MLP隐藏层维度与嵌入维度的比率
        qkv_bias (bool, optional): 是否为QKV矩阵添加可学习偏置，默认为True
        qk_scale (float | None, optional): 覆盖默认的注意力缩放因子(head_dim ** -0.5)
        drop (float, optional): 普通dropout比率，默认为0.0
        attn_drop (float, optional): 注意力dropout比率，默认为0.0
        drop_path (float | tuple[float], optional): 随机深度衰减比率，默认为0.0
        norm_layer (nn.Module, optional): 归一化层类型，默认为nn.LayerNorm
        downsample (nn.Module | None, optional): 阶段末尾的下采样层，默认为None
        use_checkpoint (bool): 是否使用梯度检查点节省内存，默认为False
        fused_window_process (bool, optional): 是否使用融合窗口处理加速，默认为False
    """

    def __init__(self, dim, input_resolution, depth, num_heads, window_size,
                 mlp_ratio=4., qkv_bias=True, qk_scale=None, drop=0., attn_drop=0.,
                 drop_path=0., norm_layer=nn.LayerNorm, downsample=None, use_checkpoint=False,
                 fused_window_process=False):
        super().__init__()
        # 初始化基础参数
        self.dim = dim  # 输入特征维度 [C]
        self.input_resolution = input_resolution  # 输入特征图尺寸 [H, W]
        self.depth = depth  # 当前阶段的Swin块数量
        self.use_checkpoint = use_checkpoint  # 是否使用梯度检查点

        # 构建Swin Transformer块序列
        self.blocks = nn.ModuleList([
            SwinTransformerBlock(
                dim=dim,  # 特征维度保持不变
                input_resolution=input_resolution,  # 输入分辨率
                num_heads=num_heads,  # 注意力头数
                window_size=window_size,  # 窗口大小
                shift_size=0 if (i % 2 == 0) else window_size // 2,  # 交替使用常规窗口和移位窗口
                mlp_ratio=mlp_ratio,  # MLP扩展比例
                qkv_bias=qkv_bias,  # QKV偏置
                qk_scale=qk_scale,  # 注意力缩放因子
                drop=drop,  # dropout比率
                attn_drop=attn_drop,  # 注意力dropout比率
                drop_path=drop_path[i] if isinstance(drop_path, list) else drop_path,  # 随机深度衰减
                norm_layer=norm_layer,  # 归一化层类型
                fused_window_process=fused_window_process  # 融合窗口处理标志
            )
            for i in range(depth)  # 创建depth个Swin块
        ])

        # 构建下采样层（如果需要）
        if downsample is not None:
            # 初始化Patch Merging层
            self.downsample = downsample(input_resolution, dim=dim, norm_layer=norm_layer)
        else:
            self.downsample = None

    def forward(self, x):
        """前向传播过程

        参数:
            x: 输入特征张量 [B, H*W, C]

        返回:
            输出特征张量 [B, (H/2)*(W/2), 2*C]（如果下采样）或 [B, H*W, C]
        """
        # 逐块处理Swin Transformer块
        for blk in self.blocks:
            if self.use_checkpoint:
                # 使用梯度检查点节省内存（训练时）
                x = checkpoint.checkpoint(blk, x)
            else:
                # 常规前向传播
                x = blk(x)

        # 应用下采样层（如果存在）
        if self.downsample is not None:
            x = self.downsample(x)

        return x

    def extra_repr(self) -> str:
        """返回模块的额外描述信息

        用于打印模型结构时显示关键参数
        """
        return f"dim={self.dim}, input_resolution={self.input_resolution}, depth={self.depth}"

    def flops(self):
        """计算该层的浮点运算量(FLOPs)

        返回:
            int: 总FLOPs数量
        """
        flops = 0
        # 累加所有Swin块的FLOPs
        for blk in self.blocks:
            flops += blk.flops()

        # 累加下采样层的FLOPs（如果存在）
        if self.downsample is not None:
            flops += self.downsample.flops()

        return flops


class PatchEmbed(nn.Module):
    """图像到Patch的嵌入层，将图像分割为不重叠的patch并进行线性投影

    功能:
        1. 将输入图像划分为规则网格的patch
        2. 对每个patch进行线性投影得到嵌入向量
        3. 可选应用归一化层

    参数:
        img_size (int | tuple[int]): 输入图像尺寸，默认224
        patch_size (int | tuple[int]): patch大小，默认4
        in_chans (int): 输入图像通道数，默认3(RGB)
        embed_dim (int): 嵌入维度，默认96
        norm_layer (nn.Module | None): 归一化层类型，默认为None
    """

    def __init__(self, img_size=224, patch_size=4, in_chans=3, embed_dim=96, norm_layer=None):
        super().__init__()
        print("初始化Patch Embedding层")

        # 将尺寸参数转换为(高,宽)格式
        img_size = to_2tuple(img_size)  # (224,224)
        patch_size = to_2tuple(patch_size)  # (4,4)

        # 计算patch网格分辨率
        patches_resolution = [
            img_size[0] // patch_size[0],  # 高度方向patch数量
            img_size[1] // patch_size[1]  # 宽度方向patch数量
        ]

        # 注册为类属性
        self.img_size = img_size  # 输入图像尺寸(H,W)
        self.patch_size = patch_size  # patch尺寸(Ph,Pw)
        self.patches_resolution = patches_resolution  # patch网格尺寸(H//Ph, W//Pw)
        self.num_patches = patches_resolution[0] * patches_resolution[1]  # 总patch数

        # 通道相关参数
        self.in_chans = in_chans  # 输入通道数(3 for RGB)
        self.embed_dim = embed_dim  # 输出嵌入维度

        # 投影层：使用卷积实现patch嵌入
        self.proj = nn.Conv2d(
            in_channels=in_chans,  # 输入通道
            out_channels=embed_dim,  # 输出通道
            kernel_size=patch_size,  # 卷积核尺寸=patch尺寸
            stride=patch_size  # 步长=patch尺寸(无重叠)
        )

        # 可选归一化层
        if norm_layer is not None:
            self.norm = norm_layer(embed_dim)
        else:
            self.norm = None

    def forward(self, x):
        """前向传播过程

        参数:
            x: 输入图像张量 [B, C, H, W]

        返回:
            嵌入后的patch序列 [B, num_patches, embed_dim]

        处理流程:
            1. 验证输入尺寸
            2. 卷积投影获取patch嵌入
            3. 展平为序列格式
            4. 应用归一化(如果存在)
        """
        B, C, H, W = x.shape  # 获取输入形状

        # 验证输入尺寸匹配
        assert H == self.img_size[0] and W == self.img_size[1], \
            f"输入图像尺寸({H}*{W})与模型预设尺寸({self.img_size[0]}*{self.img_size[1]})不匹配"

        # 卷积投影：将图像分割为patch并嵌入
        # [B, C, H, W] -> [B, embed_dim, H//Ph, W//Pw]
        x = self.proj(x)

        # 展平为序列格式：
        # 1. 展平空间维度 [B, embed_dim, Ph*Pw]
        # 2. 转置为 [B, Ph*Pw, embed_dim]
        x = x.flatten(2).transpose(1, 2)

        # 应用归一化层(如果存在)
        if self.norm is not None:
            x = self.norm(x)

        return x

    def flops(self):
        """计算该层的浮点运算量(FLOPs)

        返回:
            int: 总FLOPs数量

        计算说明:
            1. 卷积投影的计算量 = Ho * Wo * embed_dim * in_chans * (Ph * Pw)
            2. 归一化层的计算量 = Ho * Wo * embed_dim
        """
        Ho, Wo = self.patches_resolution  # 输出特征图尺寸

        # 卷积FLOPs (考虑乘加操作)
        flops = Ho * Wo * self.embed_dim * self.in_chans * \
                (self.patch_size[0] * self.patch_size[1])

        # 归一化层FLOPs (均值和方差计算)
        if self.norm is not None:
            flops += Ho * Wo * self.embed_dim

        return flops


class SwinTransformer(nn.Module):
    """Swin Transformer 主模型实现

    核心特点:
        - 分层式架构 (hierarchical architecture)
        - 移位窗口注意力 (shifted window attention)
        - 逐步下采样的特征金字塔

    参数说明:
        img_size (int | tuple): 输入图像尺寸，默认224
        patch_size (int | tuple): patch大小，默认4
        in_chans (int): 输入通道数，默认3(RGB)
        num_classes (int): 分类类别数，默认1000
        embed_dim (int): 初始嵌入维度，默认96
        depths (tuple): 各阶段块数量，如[2,2,6,2]表示4个阶段分别有2,2,6,2个Swin块
        num_heads (tuple): 各阶段注意力头数，如[3,6,12,24]
        window_size (int): 局部窗口大小，默认7
        mlp_ratio (float): MLP扩展比例，默认4
        qkv_bias (bool): 是否在QKV变换中添加偏置，默认True
        qk_scale (float): 覆盖默认的注意力缩放因子，默认None
        drop_rate (float): dropout比率，默认0
        attn_drop_rate (float): 注意力dropout比率，默认0
        drop_path_rate (float): 随机深度衰减比率，默认0.1
        norm_layer (nn.Module): 归一化层类型，默认LayerNorm
        ape (bool): 是否使用绝对位置编码，默认False
        patch_norm (bool): 是否在patch嵌入后归一化，默认True
        use_checkpoint (bool): 是否使用梯度检查点节省内存，默认False
        fused_window_process (bool): 是否使用融合窗口处理加速，默认False
    """

    def __init__(self, img_size=224, patch_size=4, in_chans=3, num_classes=1000,
                 embed_dim=96, depths=[2, 2, 6, 2], num_heads=[3, 6, 12, 24],
                 window_size=7, mlp_ratio=4., qkv_bias=True, qk_scale=None,
                 drop_rate=0., attn_drop_rate=0., drop_path_rate=0.1,
                 norm_layer=nn.LayerNorm, ape=False, patch_norm=True,
                 use_checkpoint=False, fused_window_process=False, **kwargs):
        super().__init__()

        # === 1. 基础参数配置 ===
        self.num_classes = num_classes  # 分类类别数
        self.num_layers = len(depths)  # 阶段数量
        self.embed_dim = embed_dim  # 初始嵌入维度
        self.ape = ape  # 绝对位置编码标志
        self.patch_norm = patch_norm  # patch归一化标志
        self.num_features = int(embed_dim * 2 ** (self.num_layers - 1))  # 最终特征维度
        self.mlp_ratio = mlp_ratio  # MLP扩展比例

        # === 2. Patch嵌入层 ===
        self.patch_embed = PatchEmbed(
            img_size=img_size,  # 输入图像尺寸
            patch_size=patch_size,  # patch尺寸
            in_chans=in_chans,  # 输入通道
            embed_dim=embed_dim,  # 嵌入维度
            norm_layer=norm_layer if self.patch_norm else None  # 条件归一化
        )
        num_patches = self.patch_embed.num_patches  # 总patch数
        patches_resolution = self.patch_embed.patches_resolution  # patch网格分辨率
        self.patches_resolution = patches_resolution  # 保存为类属性

        # === 3. 位置编码 ===
        if self.ape:
            # 可学习的绝对位置编码 [1, num_patches, embed_dim]
            self.absolute_pos_embed = nn.Parameter(torch.zeros(1, num_patches, embed_dim))
            trunc_normal_(self.absolute_pos_embed, std=.02)  # 截断正态初始化

        self.pos_drop = nn.Dropout(p=drop_rate)  # 位置编码后的dropout

        # === 4. 随机深度衰减 ===
        dpr = [x.item() for x in torch.linspace(0, drop_path_rate, sum(depths))]  # 线性衰减序列

        # === 5. 构建分层网络 ===
        self.layers = nn.ModuleList()
        for i_layer in range(self.num_layers):
            layer = BasicLayer(
                dim=int(embed_dim * 2 ** i_layer),  # 当前阶段维度(逐层翻倍)
                input_resolution=(
                    patches_resolution[0] // (2 ** i_layer),  # 高度方向分辨率
                    patches_resolution[1] // (2 ** i_layer)  # 宽度方向分辨率
                ),
                depth=depths[i_layer],  # 当前阶段块数
                num_heads=num_heads[i_layer],  # 当前阶段头数
                window_size=window_size,  # 窗口大小
                mlp_ratio=self.mlp_ratio,  # MLP扩展比
                qkv_bias=qkv_bias,  # QKV偏置
                qk_scale=qk_scale,  # 注意力缩放
                drop=drop_rate,  # dropout
                attn_drop=attn_drop_rate,  # 注意力dropout
                drop_path=dpr[sum(depths[:i_layer]):sum(depths[:i_layer + 1])],  # 随机深度
                norm_layer=norm_layer,  # 归一化层
                downsample=PatchMerging if (i_layer < self.num_layers - 1) else None,  # 下采样
                use_checkpoint=use_checkpoint,  # 梯度检查点
                fused_window_process=fused_window_process  # 融合窗口处理
            )
            self.layers.append(layer)

        # === 6. 分类头 ===
        self.norm = norm_layer(self.num_features)  # 最终归一化
        self.avgpool = nn.AdaptiveAvgPool1d(1)  # 全局平均池化
        self.head = nn.Linear(self.num_features, num_classes) if num_classes > 0 else nn.Identity()  # 分类头

        # === 7. 权重初始化 ===
        self.apply(self._init_weights)  # 递归应用初始化方法

    def _init_weights(self, m):
        """自定义权重初始化"""
        if isinstance(m, nn.Linear):
            trunc_normal_(m.weight, std=.02)  # 截断正态分布
            if m.bias is not None:
                nn.init.constant_(m.bias, 0)  # 偏置初始化为0
        elif isinstance(m, nn.LayerNorm):
            nn.init.constant_(m.bias, 0)  # 归一化层偏置
            nn.init.constant_(m.weight, 1.0)  # 归一化层权重

    @torch.jit.ignore
    def no_weight_decay(self):
        """不进行权重衰减的参数"""
        return {'absolute_pos_embed'}

    @torch.jit.ignore
    def no_weight_decay_keywords(self):
        """不进行权重衰减的参数关键字"""
        return {'relative_position_bias_table'}

    def forward_features(self, x):
        """特征提取流程"""
        # 1. Patch嵌入
        x = self.patch_embed(x)  # [B, L, C]

        # 2. 绝对位置编码
        if self.ape:
            x = x + self.absolute_pos_embed
        x = self.pos_drop(x)  # 位置编码dropout

        # 3. 分层处理
        for layer in self.layers:
            x = layer(x)  # 通过各阶段层

        # 4. 分类准备
        x = self.norm(x)  # 最终归一化 [B, L, C]
        x = self.avgpool(x.transpose(1, 2))  # 空间维度池化 [B, C, 1]
        x = torch.flatten(x, 1)  # 展平 [B, C]
        return x

    def forward(self, x):
        """完整前向传播"""
        x = self.forward_features(x)  # 特征提取
        x = self.head(x)  # 分类预测
        return x

    def flops(self):
        """计算模型FLOPs"""
        flops = 0
        # 1. Patch嵌入层FLOPs
        flops += self.patch_embed.flops()

        # 2. 各阶段FLOPs
        for layer in self.layers:
            flops += layer.flops()

        # 3. 分类头FLOPs
        flops += self.num_features * self.patches_resolution[0] * self.patches_resolution[1] // (2 ** self.num_layers)
        flops += self.num_features * self.num_classes

        return flops